home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / QuickTime VR / MacOS / QuickDraw™ 3D 1.0.6F4 SDK / Development / 3DMF parser / 1.0 version / MF3DPC / !README.TXT next >
Encoding:
Text File  |  1995-11-07  |  7.2 KB  |  177 lines  |  [TEXT/dosa]
  1. QuickDraw 3D Metafile Read/Write API routines
  2.  
  3. ################################################################################
  4. # What are the MF3D Routines?
  5. ################################################################################
  6.  
  7. The MF3D routines are a set of ANSI C source code files which allow developers
  8. who are not running QuickDraw 3D to read and to write QuickDraw 3D metafiles.
  9. The interface to the MF3D routines has been designed to be simple, however, it
  10. is assumed that anyone using these routines has a thorough understanding of
  11. the QuickDraw 3D metafile format. Such an understanding is especially important
  12. when writing files because these routines will not check, for example, that
  13. vertex attribute sets do not appear outside containers or that labels only
  14. appear on referenceable objects.
  15.  
  16. ################################################################################
  17. # Using the MF3D Routines
  18. ################################################################################
  19.  
  20. First, make sure that the types in "MF3DSysTypes.h" are defined as appropriate
  21. for your platform and system. If you alter the definition of the 64-bit integer
  22. types, then make sure that the macros in "MF3DInt64.h" are correct.
  23.  
  24. To read QuickDraw 3D metafiles:
  25. 1.    Call MF3DOpenInputStdCFile to open the file. MF3DOpenInputStdCFile requires
  26.     a standard C path name and returns an MF3D_FilePtr which you will use to
  27.     call the other MF3D routines. MF3DOpenInputStdCFile determines what kind of
  28.     file is being read, loads any tables of contents, and does some basic
  29.     sanity checks on the format.
  30. 2.    Call MF3DReadAnObject to read an object. The object will be returned as
  31.     type MF3DVoidObjPtr. You must then check object->objectType to find out
  32.     what type of object you have and cast the pointer as appropriate. All the
  33.     types and structures are defined in "MF3DObjects.h" and "MF3DSubObjects.h".
  34.     When you are finished with the object, call MF3DDisposeObject.
  35. 3.    Repeat Step 2 until kMF3DNoMoreObjects is returned.
  36. 4.    Call MF3DClose to clean up any internal data and to close the file.
  37.  
  38. To write QuickDraw 3D metafiles:
  39. 1.    Call MF3DOpenOutputStdCFile to open the file.
  40. 2.    Call MF3DWriteAnObject to write an object. The object you pass should be
  41.     one of the objects defined in "MF3DObjects.h" and "MF3DSubObjects.h".
  42. 3.    Repeat Step 2 until you have no more objects to write.
  43. 4.    Call MF3DClose to write the Table of Contents and to close the file.
  44.  
  45. ################################################################################
  46. # EndContainer object
  47. ################################################################################
  48.  
  49. Because the MF3D routines only work on an object at a time, an EndContainer
  50. object is used to mark the end of Container. The EndContainer object is not part
  51. of the QuickDraw 3D metafile specification, but should nevertheless be treated
  52. just like any other object when using the MF3D routines.
  53.  
  54. ################################################################################
  55. # Sample Code
  56. ################################################################################
  57.  
  58. main.c
  59.     Sample application that asks for a file (text or binary), reads objects
  60.     from that file, and writes them back out into a new text file.
  61. MPWMain.c
  62.     Sample MPW tool that accepts a parameter as the filename, reads objects
  63.     from that file, and writes them back out into a new binary file.
  64. MPWRefExample.c
  65.     Sample MPW tool that shows how to resolve internal and external references
  66.     which are read from a metafile.
  67. MPWTest.make
  68.     MPW Makefile that will build a tool using MPWMain.c
  69. MWPPC.Ê
  70.     Metrowerks C++ project that will build an application using main.c
  71.  
  72. ################################################################################
  73. # File Descriptions
  74. ################################################################################
  75.  
  76. #
  77. # External header files
  78. #    Anyone using the MF3D source code will be interested in these files
  79. #
  80. MF3D.h
  81.     External interface to the MF3D routines. Most applications should not need
  82.     to access any other routines.
  83. MF3DErrors.h
  84.     Various error codes returned by the MF3D routines.
  85. MF3DInt64.h
  86.     Macros needed to support usage of 64-bit integers. These need to be
  87.     updated if the definition of MF3DInt64 is changed in "MF3DTypes.h".
  88. MF3DObjects.h
  89.     Structural definition of the main (top-level) QuickDraw 3D Metafile
  90.     objects that can be returned.
  91. MF3DSubObjects.h
  92.     Structural definition of the other QuickDraw 3D Metafile objects that
  93.     can be returned. These objects are generally found inside a container.
  94. MF3DSysTypes.h
  95.     Basic system-dependent typedefs. These must be defined as appropriate
  96.     to the platform being used.
  97. MF3DTypes.h
  98.     Basic MF3D types.
  99.  
  100. #
  101. # External implementation file
  102. #
  103. MF3D.c
  104.     Implementation of MF3D external interface.
  105.  
  106. #
  107. # I/O routines
  108. #    Most developers will be able to use MF3DOpenInputStdCFile and
  109. #    MF3DOpenOutputStdCFile. Those who want to define their own I/O routines
  110. #    can use "MF3DStdCHooks.c" as an example.
  111. #
  112. MF3DIOCallback.h
  113.     Structure needed when calling MF3DOpenInput or MF3DOpenOutput directly.
  114. MF3DStdCHooks.c
  115. MF3DStdCHooks.h
  116.     Implementation to support MF3DOpenInputStdCFile and MF3DOpenOutputStdCFile.
  117.  
  118. #
  119. # Internal files
  120. #    These files will only be of interest to those who have a desire to
  121. #    modify the inner workings of the MF3D routines. Each internal file contains
  122. #    an underscore in its name. Also, the routines and types defined in these
  123. #    files also have underscores in their names.
  124. #
  125. MF3D_Assert.h
  126.     Set DEBUG to 1 if asserts are desired.
  127. MF3D_BinaryRead.c
  128. MF3D_BinaryRead.h
  129.     Miscellaneous functions to handle reading binary files.
  130. MF3D_File.c
  131. MF3D_File.h
  132.     Miscellaneous functions that mostly handle cleanup during close.
  133. MF3D_Groups.c
  134. MF3D_Groups.h
  135.     Functions that are available that could keep track of data when pushing
  136.     and popping groups. In Release 1.0 of MF3D, these functions essentially
  137.     do nothing.
  138. MF3D_IntObjects.h
  139.     Internal structures, including the MF3D_FilePtr.
  140. MF3D_Labels.c
  141. MF3D_Labels.h
  142.     Enum and Flags tables and lookup routines.
  143. MF3D_Macros.h
  144.     A couple of common macros.
  145. MF3D_Memory.c
  146. MF3D_Memory.h
  147.     Memory allocation routines. These could be replaced by those who
  148.     want to call platform-specific routines instead of the standard C library
  149.     routines.
  150. MF3D_Objects.c
  151. MF3D_Objects.h
  152.     All the functions which handle reading, writing, and disposing of the
  153.     various QuickDraw 3D Metafile objects.
  154. MF3D_ObjectType.c
  155.     Functions to convert between ASCII names and Binary types.
  156. MF3D_ObjectType.h
  157.     Tables linking ASCII names, Binary types, and read/write/dispose functions
  158.     of the various QuickDraw 3D Metafile objects.
  159. MF3D_Primitives.c
  160. MF3D_Primitives.h
  161.     Lower-level functions that handle reading and writing of basic types
  162.     (Text/Binary-independent).
  163. MF3D_Resolution.c
  164. MF3D_Resolution.h
  165.     Functions that keep track of things when resolving references.
  166. MF3D_TextRead.c
  167. MF3D_TextRead.h
  168.     Miscellaneous functions to handle reading text files.
  169. MF3D_TextStrings.h
  170.     Equates for various QuickDraw 3D Metafile characters.
  171. MF3D_TextUtils.c
  172. MF3D_TextUtils.h
  173.     Miscellaneous string utility functions.
  174. MF3D_TextWrite.c
  175. MF3D_TextWrite.h
  176.     Miscellaneous functions to handle writing text files.
  177.